home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1996 #6 / Amiga Plus CD - 1996 - No. 06.iso / pd / programmierung / programmers / mmd_fileformat.doc < prev    next >
Text File  |  1996-06-23  |  40KB  |  1,034 lines
  1. -----------------------------------------------------------------------------
  2.  
  3.         MED/OctaMED MMD0/MMD1/MMD2/MMD3 file formats
  4.         written by Teijo Kinnunen (01.02.1996)
  5.         Revision 6
  6.  
  7. $VER: MMD_documentation 6 (01.02.1996)
  8.  
  9. -----------------------------------------------------------------------------
  10.  
  11. Background
  12. ~~~~~~~~~~
  13. A couple of years ago, when programming MED V2.1, I needed a file format for
  14. MED modules. The only "module" format in MED V2.0 was the Sng+samples format.
  15. Although it produced compact files, it was very difficult and tricky to read
  16. in. Therefore, I designed a new file format, that would be easy to use in
  17. module player programs etc. This file format was named 'MMD0' (Med MoDule 0).
  18. The limitations in MMD0 block format forced me to create a new file format
  19. for OctaMED Professional, this format is 'MMD1'. It's mostly the same as
  20. MMD0, except the block structure is different. Another new format is called
  21. 'MMD2', this extends some of the old limits and provides a couple of new
  22. features. 'MMD3' is identical to 'MMD2', but programs supporting this
  23. format must be able to recognize mixing mode of OctaMED Soundstudio. (This
  24. new id was introduced so that old program would not try to play modules they
  25. really can't.) Note that 'V7' in the following documentation refers to
  26. OctaMED Soundstudio V1.
  27.  
  28. Design concepts
  29. ~~~~~~~~~~~~~~~
  30. One of the main goals was to make MMD's (MED modules) as extensible as
  31. possible. This would have been easy to implement with IFF-style chunks.
  32. However, this method was obviously not the best for play-routine use.
  33.  
  34. Therefore, MMD's are implemented in quite an extraordinary way. They consist
  35. of structures (similar to C structs), and pointers. In a module file,
  36. pointers are defined as offsets from the beginning of the module. This way, a
  37. particular structure can be read just by Seek()'ing using the pointer as the
  38. offset from the beginning of the file. When a module has been read into
  39. memory, it has to be relocated before it can be used (the relocation is done
  40. simply by adding the address of the module to the pointers).
  41.  
  42. As with the Amiga OS, a MMD file does not contain absolute addresses. There's
  43. a module header structure at the beginning of the file. This structure
  44. contains pointers to different parts of the module. And you *MUST* use these
  45. pointers. You may NOT expect that the song structure is at offset $00000034,
  46. for example. Although it usually is, this may change in future releases. In
  47. addition, it's possible that a structure even doesn't exist (the structure
  48. pointer is NULL). Therefore, you *MUST* check the structure pointer before
  49. accessing the structure. Finally, when writing MMD's you *MUST* set
  50. undefined/reserved fields to zeros. More finally, you *MUST* align all
  51. structures to even boundaries! (I forgot the alignment in MED V3.00 save
  52. routine, resulting Guruing modules under some conditions :-(
  53.  
  54. The module header
  55. ~~~~~~~~~~~~~~~~~
  56. This structure must exist at the beginning of each MED module file. Each of
  57. the structure members are described.
  58.  
  59. In multi-modules, there are header structs for each song. (The subsequent
  60. header pointers can be found from expdata structure. Multi-modules should
  61. have the same smplarr pointer in every header.) Older MEDs which don't
  62. recognize multi-modules consider a multi-module as an ordinary module (only
  63. the first song is loaded).
  64.  
  65. The numbers enclosed in /* */ at the beginning of each line are (decimal)
  66. offsets of each member (for assembly programmers).
  67.  
  68. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  69. struct MMD0 {
  70. /* 0 */     ULONG   id;
  71. /* 4 */     ULONG   modlen;
  72. /* 8 */     struct MMD0song *song;
  73. /* 12 */    UWORD   psecnum;    /* for the player routine, MMD2 only */
  74. /* 14 */    UWORD   pseq;       /*  "   "   "   "    */
  75. /* 16 */    struct MMD0Block **blockarr;
  76. /* 20 */    UBYTE   mmdflags;
  77. /* 21 */    UBYTE   reserved[3];
  78. /* 24 */    struct InstrHdr **smplarr;
  79. /* 28 */    ULONG   reserved2;
  80. /* 32 */    struct MMD0exp *expdata;
  81. /* 36 */    ULONG   reserved3;
  82. /* 40 */    UWORD   pstate;  /* some data for the player routine */
  83. /* 42 */    UWORD   pblock;
  84. /* 44 */    UWORD   pline;
  85. /* 46 */    UWORD   pseqnum;
  86. /* 48 */    WORD    actplayline;
  87. /* 50 */    UBYTE   counter;
  88. /* 51 */    UBYTE   extra_songs; /* number of songs - 1 */
  89. }; /* length = 52 bytes */
  90.  
  91. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  92. id
  93. --
  94. This longword is used to identify the MMD and its version. Currently defined
  95. MMD types are MMD0 (0x4D4D4430), MMD1 (0x4D4D4431), MMD2 (0x4D4D4432) and
  96. MMD3 (0x4D4D4433). MMD4 and upwards are reserved for future versions. Note
  97. that MMD2 and MMD3 file formats are identical (some notes exist below,
  98. though).
  99.  
  100. In multi-modules, the following modules usually contain id MCNT, MCN1, MCN2
  101. or MCN3. The first module always has MMD0 - MMD3 as an id.
  102.  
  103. modlen
  104. ------
  105. This longword contains the length of the entire module.
  106.  
  107. song
  108. ----
  109. Pointer to a MMD0song/MMD2song structure. This structure MUST ALWAYS EXIST!
  110.  
  111. blockarr
  112. --------
  113. Pointer to a table of block pointers. For example:
  114.     blockarr:  $00003000
  115.             block 0 ptr block 1 ptr block 2 ptr
  116. offset  $00003000:  $00002000,  $00002400,  $00002800 ....
  117.  
  118. offset  $00002000: block 0 data...
  119. offset  $00002400: block 1 data...
  120. ...
  121. The size of the table is MMD0song.numblocks longwords.
  122.  
  123. mmdflags
  124. --------
  125. This field contains generic flags of the module. Only one flag is currently
  126. defined:
  127.  
  128.     MMD_LOADTOFASTMEM    0x1
  129.  
  130. This flag instructs the loading routine (LoadModule) to always read this
  131. module into fast RAM (if it uses mixing, 8 ch mode or no samples). Not all
  132. versions of OctaMED write this flag.
  133.  
  134. smplarr
  135. -------
  136. Pointer to a table of instrument pointers. The size of the table is
  137. MMD0song.numsamples longwords. This pointer is zero in OctaMED Pro MMD1 songs.
  138. In this case, OctaMED Pro loads the instruments from disk(s).
  139.  
  140. expdata
  141. -------
  142. Pointer to an expansion structure. The expansion structure contains a lot of
  143. extra information. The exp. structure does not exist in all MMD's. (Be sure
  144. to check the pointer before using it.)
  145.  
  146. pstate, pblock, pline, pseqnum, actplayline, counter, psecnum, pseq
  147. -------------------------------------------------------------------
  148. These are variables for the play routine. You can read these fields to get
  149. the current song position (not all versions of the play routine use these
  150. fields, however). When writing a MMD, you should leave all fields to zero,
  151. except the 'actplayline', which ought to be -1 ($FFFF).
  152.  
  153. extra_songs
  154. -----------
  155. This field contains the number of songs in the current module. For
  156. non-multi-modules, this is 0. If there are two songs, extra_songs contains 1,
  157. and so on.
  158.  
  159. reserved0,1,2,3
  160. ---------------
  161. Not currently defined. Set to zero.
  162.  
  163.  
  164. The song structure (MMD0song)
  165. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  166. This structure contains the basic information about the song. It must exist
  167. on every module file. This structure is for MMD0/MMD1 only! The MMD2 struct
  168. is documented below.
  169.  
  170. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  171. struct MMD0song {
  172.     struct MMD0sample sample[63];   /* 63 * 8 bytes = 504 bytes */
  173.     UWORD   numblocks;      /* offs: 504 */
  174.     UWORD   songlen;        /* offs: 506 */
  175.     UBYTE   playseq[256];   /* offs: 508 */
  176.     UWORD   deftempo;       /* offs: 764 */
  177.     BYTE    playtransp;     /* offs: 766 */
  178.     UBYTE   flags;          /* offs: 767 */
  179.     UBYTE   flags2;         /* offs: 768 */
  180.     UBYTE   tempo2;         /* offs: 769 */
  181.     UBYTE   trkvol[16];     /* offs: 770 */
  182.     UBYTE   mastervol;      /* offs: 786 */
  183.     UBYTE   numsamples;     /* offs: 787 */
  184. }; /* length = 788 bytes */
  185.  
  186. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  187. sample
  188. ------
  189. Contains some basic info about each sample. The structure looks like this:
  190.  
  191. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  192.     struct MMD0sample {
  193.         UWORD rep,replen;   /* offs: 0(s), 2(s) */
  194.         UBYTE midich;       /* offs: 4(s) */
  195.         UBYTE midipreset;   /* offs: 5(s) */
  196.         UBYTE svol;         /* offs: 6(s) */
  197.         BYTE strans;        /* offs: 7(s) */
  198.     };
  199.  
  200. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  201.     rep         repeat start offset, shifted right one bit (as in
  202.                 Protracker).
  203.     replen      repeat length, shifted right one bit.
  204.     midich      MIDI channel for current instrument, 0 if not MIDI.
  205.     midipreset  MIDI preset number for current instrument, 0 if no preset.
  206.     svol        default volume for current instrument (0 - 64).
  207.     strans      instrument transpose value.
  208.  
  209. More information is defined in expdata structure.
  210.  
  211. numblocks
  212. ---------
  213. Number of blocks in current song. This field also indicates the length of the
  214. blockarr table in longwords.
  215.  
  216. songlen
  217. -------
  218. Song length (number of sequence numbers in the play sequence list).
  219.  
  220. playseq
  221. -------
  222. This is the play sequence list.
  223.  
  224. deftempo
  225. --------
  226. Default song tempo (the main tempo slider in MED/OctaMED). If BPM mode is on,
  227. this value indicates BPM.
  228.  
  229. playtransp
  230. ----------
  231. The global play transpose value for current song.
  232.  
  233. flags
  234. -----
  235. Contains many single-bit flags:
  236.     FLAG_FILTERON   0x1     the hardware audio filter is on
  237.     FLAG_JUMPINGON  0x2     mouse pointer jumping on (not in OctaMED Pro)
  238.     FLAG_JUMP8TH    0x4     jump every 8th line (not in OctaMED Pro)
  239.     FLAG_INSTRSATT  0x8     sng+samples indicator (not useful in MMD's)
  240.     FLAG_VOLHEX     0x10    volumes are HEX
  241.     FLAG_STSLIDE    0x20    use ST/NT/PT compatible sliding
  242.     FLAG_8CHANNEL   0x40    this is OctaMED 5-8 channel song
  243.     FLAG_SLOWHQ     0X80    HQ V2-4 compatibility mode
  244.  
  245. flags2
  246. ------
  247. More flags:
  248.     FLAG2_BMASK 0x1F (bits 0-4)     BPM beat length (in lines)
  249.                                     0 = 1 line, $1F = 32 lines.
  250.                                     (OctaMED Pro Lines Per Beat slider.)
  251.     FLAG2_BPM   0x20    BPM mode on
  252.     FLAG2_MIX   0x80    This flag implies that the module uses mixing.
  253.  
  254.     (bit 0x40 is not defined, and must be set to zero)
  255.  
  256. tempo2
  257. ------
  258. This is the "secondary tempo" (the rightmost MED/OctaMED tempo slider),
  259. indicating the number of timing pulses per line.
  260.  
  261. trkvol[16]
  262. ----------
  263. The relative track volumes (1 - 64) for each track.
  264.  
  265. mastervol
  266. ---------
  267. The relative master volume (1 - 64).
  268.  
  269. numsamples
  270. ----------
  271. Number of instruments (samples/synthsounds) in current song. Also indicates
  272. the size of the smplarr table in longwords.
  273.  
  274. The MMD2 song structure
  275. ~~~~~~~~~~~~~~~~~~~~~~~
  276. struct MMD2song {
  277.     struct MMD0sample sample[63];
  278.     UWORD   numblocks;
  279.     UWORD   songlen;    /* NOTE: number of sections in MMD2 */
  280.     struct  PlaySeq **playseqtable;
  281.     UWORD   *sectiontable;  /* UWORD section numbers */
  282.     UBYTE   *trackvols; /* UBYTE track volumes */
  283.     UWORD   numtracks;  /* max. number of tracks in the song
  284.                            (also the number of entries in
  285.                            'trackvols' table) */
  286.     UWORD   numpseqs;   /* number of PlaySeqs in 'playseqtable' */
  287.     BYTE    *trackpans;        /* NULL means 'all centered */
  288.     ULONG   flags3;        /* see defs below */
  289.     UWORD   voladj;        /* volume adjust (%), 0 means 100 */
  290.     UWORD   channels;        /* mixing channels, 0 means 4 */
  291.     UBYTE   mix_echotype;    /* 0 = nothing, 1 = normal, 2 = cross */
  292.     UBYTE   mix_echodepth;    /* 1 - 6, 0 = default */
  293.     UWORD   mix_echolen;    /* echo length in milliseconds */
  294.     BYTE    mix_stereosep;    /* stereo separation */
  295.     UBYTE   pad0[223];        /* reserved for future expansion */
  296. /* Below fields are MMD0/MMD1-compatible (except pad1[]) */
  297.     UWORD   deftempo;
  298.     BYTE    playtransp;
  299.     UBYTE   flags;
  300.     UBYTE   flags2;
  301.     UBYTE   tempo2;
  302.     UBYTE   pad1[16];   /* used to be trackvols, in MMD2 reserved */
  303.     UBYTE   mastervol;
  304.     UBYTE   numsamples;
  305. };
  306.  
  307. This structure is exactly as long as the MMDsong structure. Common fields are
  308. located at same offsets. You can also see, that there's a lot of room for
  309. expansion in this structure. The new/changed fields are:
  310.  
  311. songlen
  312. -------
  313. Now expresses the number of sections (i.e. the length of 'sectiontable').
  314.  
  315. playseqtable
  316. ------------
  317. Points to a table of PlaySeq structures. This structure is:
  318.  
  319.     struct PlaySeq {
  320.         char    name[32];       /* (0)  31 chars + \0 */
  321.         ULONG   reserved[2];    /* (32) for possible extensions */
  322.         UWORD   length;         /* (40) # of entries */
  323.     /* Commented out, not all compilers may like it... */
  324.     /*  UWORD   seq[0]; */      /* (42) block numbers.. */
  325.     };
  326.  
  327. This should be self-explaining. Note: block numbers in seq[] may not be
  328. greater than 0x7FFF. These are reserved for future expansions. The current
  329. player routines skip these numbers.
  330.  
  331. trackvols
  332. ---------
  333. Points to a table of 'numtracks' UBYTEs, which contain values 1 - 64 for
  334. relative track volumes.
  335.  
  336. numtracks
  337. ---------
  338. The number of tracks this song uses (i.e. the width of the widest block).
  339.  
  340. numpseqs
  341. --------
  342. The number of PlaySeqs in 'playseqtable'.
  343.  
  344. trackpans
  345. ---------
  346. Points to a table of 'numtracks' BYTEs, which contain values -16 - 16 for
  347. panpot positions of tracks.
  348.  
  349. flags3
  350. ------
  351. These flags:
  352.     FLAG3_STEREO     0x1    Mixing in stereo
  353.     FLAG3_FREEPAN    0x2    Mixing flag: free pan
  354.  
  355. voladj
  356. ------
  357. Volume adjust value of the module (mixing). Value 0 equals volume adjust
  358. 100.
  359.  
  360. channels
  361. --------
  362. Max. number of mixing channels. Value 0 equals 4.
  363.  
  364. mix_echotype
  365. ------------
  366. Currently these echo types are defined (this is an ordinal number, not
  367. a bit field):
  368.     0 = none
  369.     1 = normal
  370.     2 = cross echo
  371.  
  372. mix_echodepth
  373. -------------
  374. Echo depth, currently these values are defined:
  375.     0 = default
  376.     1 = 50 %
  377.     2 = 25 %
  378.     3 = 12.5 %
  379.     4 = 6.25 %
  380.     5 = 3.125 %
  381.     6 = 1.5625 %
  382.  
  383. mix_echolen
  384. -----------
  385. Echo length in milliseconds.
  386.  
  387. mix_stereosep
  388. -------------
  389. Stereo separation (-4 - 4).
  390.  
  391. pad[]
  392. -----
  393. Must be zero! Don't attempt to read.
  394.  
  395. The block format
  396. ~~~~~~~~~~~~~~~~
  397. As described above, MMD0 header structure contains a pointer (blockarr) to a
  398. table of block pointers. These block pointers point to the actual block data
  399. structures. The format of these data structures differ in MMD0 and MMD1 file
  400. formats.
  401.  
  402. MMD0 block format
  403. -----------------
  404. At the beginning of each block, there's a small header:
  405.  
  406. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  407.     struct MMD0Block {
  408.         UBYTE numtracks,lines;
  409.     };
  410.  
  411. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  412.     numtracks   number of tracks (4, 8, 12 or 16) on this block
  413.     lines       number of lines on this block; 0 = 1 line,
  414.                 255 = 256 lines
  415.  
  416. Following this header, there is the actual note data, consisting of 3-byte
  417. structures containing a note and its command. The data is arranged
  418. sequentially a line at a time, i.e. in the following order:
  419.     line 0 track 0
  420.     line 0 track 1
  421.     line 0 track 2
  422.     line 0 track 3
  423.     line 1 track 0
  424.     line 1 track 1
  425.     ...
  426. The 3-byte structure looks like this (each letter corresponds to one bit):
  427.  
  428.     xynnnnnn iiiicccc dddddddd
  429.  
  430.     n = note number (0 - $3F). 0 = ---, 1 = C-1, 2 = C#1...
  431.     i = the low 4 bits of the instrument number
  432.     x = the 5th bit (#4) of the instrument number
  433.     y = the 6th bit (#5) of the instrument number
  434.     c = command number (0 - $F)
  435.     d = databyte ($00 - $FF)
  436.  
  437. MMD1/MMD2 block format
  438. -----------------
  439. MMD1/MMD2 block format can contain a lot more information than MMD0's. The
  440. block header looks like this:
  441.  
  442. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  443.     struct MMD1Block {
  444.         UWORD numtracks;
  445.         UWORD lines;
  446.         struct BlockInfo *info;
  447.     };
  448.  
  449. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  450.     numtracks   Number of tracks in this block (4, 8, 12, or 16).
  451.                 (MMD2: All values between 1 - 64 are valid.)
  452.     lines       Number of lines in this block (0 = 1 line etc.).
  453.                 OctaMED Pro can handle upto 3200 lines/block, so
  454.                 this is obviously the practical upper limit.
  455.     info        Pointer to structure containing extra information.
  456.                 (Can be NULL, if no BlockInfo struct exists).
  457.  
  458.     The BlockInfo structure is:
  459.  
  460. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  461.     struct BlockInfo {
  462.         ULONG   *hlmask;
  463.         UBYTE   *blockname;
  464.         ULONG   blocknamelen;
  465.         struct  BlockCmdPageTable *pagetable;
  466.         ULONG   reserved[5];
  467.     };
  468.  
  469. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  470.     hlmask      Pointer to an array of longwords, containing info
  471.                 about line highlighting (TAB key on MED). The number
  472.                 of longwords depend on the number of lines on the
  473.                 block. (E.g: 1 line -> 1 longword, 32 lines -> 1 lw,
  474.                 33 lines -> 2 lws, 256 lines -> 4 lws)
  475.                 The bits in the longwords are arranged in reversed
  476.                 order (e.g. bit #0 = line 0, bit #31 = line 31).
  477.  
  478.     blockname   Pointer to the name of the block. Must be null-
  479.                 terminated.
  480.  
  481.     blocknamelen    Length of the block name, including the terminating
  482.                     zero. OctaMED Pro currently has the maximum length of
  483.                     41 chars (+ zero). However, this may change in the
  484.                     future. Don't read blocknames longer than you are
  485.                     able to handle!
  486.  
  487.     pagetable   OctaMED V6 supports multiple player commands per note.
  488.                 This pointer points to the BlockCmdPageTable structure,
  489.                 if this block has more than one pages. (See below.)
  490.  
  491.     reserved[5] These are reserved for future extensions. Must be set   
  492.                 to zero.
  493.  
  494.     This is the BlockCmdPageTable structure:
  495.  
  496. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  497. struct BlockCmdPageTable {
  498.     UWORD    num_pages;
  499.     UWORD    reserved;
  500.     UWORD    *page[0];
  501. };
  502.  
  503. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  504.  
  505.     num_pages   Specifies the number of additional command pages. The first
  506.                 command page that always exists is not included in this.
  507.  
  508.     reserved    Some room for future expansions, you never know..
  509.  
  510.     page        Here begins the table of command page pointers. (The table
  511.                 has num_pages entries.) Each page contains two-byte entries
  512.                 (command and data byte), which are arranged just as notes
  513.                 in blocks. (Line 0 Track 0, Line 0 Track 1...)
  514.  
  515.     The note structures, which are 4 bytes long in MMD1 modules, are
  516.     arranged exactly as in MMD0 modules (i.e. L0T0, L0T1... L1T0, L1T1..).
  517.  
  518.         xnnnnnnn xxiiiiii cccccccc dddddddd
  519.  
  520.     n = note number (0 - $7F, 0 = ---, 1 = C-1...)
  521.     i = instrument number (0 - $3F)
  522.     c = command ($00 - $FF)
  523.     d = data byte ($00 - $FF)
  524.     x = undefined, reserved for future expansion. MUST BE SET TO ZERO,
  525.         AND MASKED OUT WHEN READING THE NOTE OR INSTRUMENT NUMBER.
  526.  
  527.  
  528. The instrument format
  529. ~~~~~~~~~~~~~~~~~~~~~
  530. The MMD0 header structure contains a pointer (smplarr) to a table of
  531. instrument pointers. These pointers point to the actual instrument data
  532. structures. If an instrument pointer is zero, there's no instrument in that
  533. slot.
  534.  
  535. Every instrument has a six-byte header structure, which is the same for all
  536. instrument types (sample/synth/hybrid).
  537.  
  538. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  539.     struct InstrHdr {
  540.         ULONG   length;
  541.         WORD    type;
  542.         /* Followed by actual data */
  543.     };
  544.  
  545. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  546.     length      indicates the length of the instrument (the six byte
  547.                 header data length is not included)
  548.     type        instrument type - currently the following types are
  549.                 defined:
  550.  
  551.         HYBRID      -2
  552.         SYNTHETIC   -1
  553.         SAMPLE      0   (an ordinary 1-octave sample)
  554.         IFF5OCT     1   (5 octaves)
  555.         IFF3OCT     2   (3 octaves)
  556.         (The following ones are recognized by OctaMED Pro only)
  557.         IFF2OCT     3   (2 octaves)
  558.         IFF4OCT     4   (4 octaves)
  559.         IFF6OCT     5   (6 octaves)
  560.         IFF7OCT     6   (7 octaves)
  561.         (OctaMED Pro V5 + later)
  562.         EXTSAMPLE   7   (two extra-low octaves)
  563.  
  564. The sample-type instruments (>= 0) contain the actual sample data straight
  565. after the header structure.
  566.  
  567. Since OctaMED V6, there are also two flag bits in the type field:
  568.         S_16        0x10
  569.         STEREO      0x20
  570.  
  571. S_16 means that this is a 16-bit sample. Length still indicates the sample
  572. length in bytes, so there are actually length / 2 16-bit samples.
  573.  
  574. STEREO means that this is a stereo sample. The sample is not interleaved. The
  575. left channel comes first, followed by the right channel. Important: Length
  576. specifies the size of one channel only! The actual memory usage for both
  577. samples is length * 2 bytes.
  578.  
  579. Plus an obsolete item:
  580.         OBSOLETE_MD16    0x18
  581.  
  582. This instrument type is obsolete, and was used for V5.04 Aura support. It
  583. should be treated as type S_16|SAMPLE (0x10), with instrument's output device
  584. set to Aura.
  585.  
  586. Synthetic instruments
  587. ---------------------
  588. Synthsounds have a special structure of their own. They also contain
  589. waveforms and pointers to them. Therefore, relocation is required. However,
  590. there's an important difference: pointers are expressed as an offset from the
  591. beginning of the synthsound, NOT the beginning of the module. The 'reloc.a'
  592. routine provided with MED/OctaMED automatically handles this.
  593.  
  594. The synthsound structure is as follows (note that this structure contains the
  595. header structure):
  596.  
  597. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  598.     struct SynthInstr {
  599.         ULONG   length;     /* length of this struct */
  600.         WORD    type;       /* -1 or -2 (offs: 4) */
  601.         UBYTE   defaultdecay;
  602.         UBYTE   reserved[3];
  603.         UWORD   rep;
  604.         UWORD   replen;
  605.         UWORD   voltbllen;  /* offs: 14 */
  606.         UWORD   wftbllen;   /* offs: 16 */
  607.         UBYTE   volspeed;   /* offs: 18 */
  608.         UBYTE   wfspeed;    /* offs: 19 */
  609.         UWORD   wforms;     /* offs: 20 */
  610.         UBYTE   voltbl[128];    /* offs: 22 */
  611.         UBYTE   wftbl[128]; /* offs: 150 */
  612.         struct  SynthWF *wf[64]; /* offs: 278 */
  613.     };
  614.  
  615. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  616.     defaultdecay    = the default decay of the current synthsound. This
  617.                       is NOT used in modules. It's significant only when
  618.                       saving a single synthsound.
  619.  
  620.     reserved[3] = set to zero.
  621.  
  622.     rep, replen = repeat/rep. length for hybrid sounds. Used only
  623.                   when saving a single hybrid sound.
  624.  
  625.     voltbllen   = the length of the volume sequence table.
  626.  
  627.     wftbllen    = the length of the waveform sequence table.
  628.  
  629.     volspeed    = the initial volume table execution speed.
  630.  
  631.     wfspeed     = the initial waveform table execution speed.
  632.  
  633.     wforms      = the number of waveforms in the current synthsound.
  634.  
  635.     voltbl      = the actual volume sequence table. Values $00-$7F
  636.                   are volumes or command arguments. Values >= $80 are
  637.                   commands. The following commands are currently
  638.                   defined:
  639.                 $FF END     $F4 EN1
  640.                 $FE JMP     $F3 CHU
  641.                 $FB HLT     $F2 CHD
  642.                 $FA JWS     $F1 WAI
  643.                 $F6 EST     $F0 SPD
  644.                 $F5 EN2
  645.  
  646.     wftbl       = the actual waveform sequence table. Values $00-$7F
  647.                   are waveform numbers  or command arguments. Values
  648.                   >= $80 are commands. The following commands are
  649.                   currently defined:
  650.                 $FF END     $F6 RES
  651.                 $FE JMP     $F5 VBS
  652.                 $FD ARE     $F4 VBD
  653.                 $FC ARP     $F3 CHU
  654.                 $FB HLT     $F2 CHD
  655.                 $FA JVS     $F1 WAI
  656.                 $F7 VWF     $F0 SPD
  657.  
  658.     wf      = pointers to waveforms. (Once again: relative to the
  659.               beginning of the synthsound!) A waveform structure
  660.               is as follows:
  661.  
  662.                 struct SynthWF {
  663.                     UWORD length;   /* length in words */
  664.                     BYTE  wfdata[xx]; /* the waveform */
  665.                 };
  666.  
  667.                 (where xx = length in bytes)
  668.  
  669.               In hybrid sounds, however, wf[0] is different.
  670.  
  671. Hybrid instruments
  672. ------------------
  673. Hybrid sounds use the same structure as synthsounds, except that the first
  674. waveform (wf[0]) pointer points to a sample. (The sample header structure
  675. exists, as usual.)
  676.  
  677.  
  678. MMD0exp - the key to future expansions
  679. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  680. For possible future expansions, I designed a structure for carrying the
  681. miscellaneous things that were added to MED/OctaMED now and then. (MED V3.00
  682. was the first version, which wrote this structure.) Most of its fields are in
  683. use now, but it's possible to even expand this structure (things will get a
  684. bit more tricky, though).
  685.  
  686. In multi-modules, you should extract all data from the expansion structure of
  687. the first song. The only exceptions are currently the 'nextmod' and
  688. 'songname' fields, which are song-specific.
  689.  
  690. Also, there has been need for extending the MMD0sample structure. Both
  691. InstrExt and MMDInstrInfo provide extra information about the instruments.
  692. These are defined as structure arrays (exp_smp and iinfo point to the first
  693. structure). The extension structures don't have a constant size, instead you
  694. have to read s_ext_entrsz or i_ext_entrsz to get the structure sizes. When
  695. reading, you have to check the entrsz fields to see which structure members
  696. do exist. See the MMD3 note below for s_ext_entries!!
  697.  
  698. The difference between InstrExt and MMDInstrInfo is that InstrExt contains
  699. information the play-routine is interested in (e.g. finetune). MMDInstrInfo
  700. contains "secondary" information, which is of no use to the player routine
  701. (e.g. instrument name).
  702.  
  703. The expansion structure follows:
  704.  
  705. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  706.     struct MMD0exp {
  707.         struct MMD0 *nextmod;
  708.         struct InstrExt *exp_smp;
  709.         UWORD  s_ext_entries;
  710.         UWORD  s_ext_entrsz;
  711.         UBYTE  *annotxt;
  712.         ULONG  annolen;
  713.         struct MMDInstrInfo *iinfo;
  714.         UWORD  i_ext_entries;
  715.         UWORD  i_ext_entrsz;
  716.         ULONG  jumpmask;
  717.         UWORD  *rgbtable;
  718.         UBYTE  channelsplit[4];
  719.         struct NotationInfo *n_info;
  720.         UBYTE  *songname;
  721.         ULONG  songnamelen;
  722.         struct MMDDumpData *dumps;
  723.         struct MMDInfo *mmdinfo;
  724.         struct MMDARexx *mmdrexx;
  725.         struct MMDMIDICmd3x *mmdcmd3x;
  726.         ULONG  reserved2[3];
  727.         ULONG  tag_end;
  728.     };
  729.  
  730. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  731.     nextmod     = pointer to the next module (or zero). (Only used in
  732.                   multi-modules!)
  733.  
  734.     exp_smp     = pointer to InstrExt. Currently the first four bytes
  735.                   of InstrExt have been defined:
  736.  
  737.                     struct InstrExt {
  738.                         UBYTE hold;
  739.                         UBYTE decay;
  740.                         UBYTE suppress_midi_off;
  741.                         BYTE  finetune;
  742.                         /* Below fields saved by >= V5 */
  743.                         UBYTE default_pitch;
  744.                         UBYTE instr_flags;
  745.                         UWORD long_midi_preset;
  746.                         /* Below fields saved by >= V5.02 */
  747.                         UBYTE output_device;
  748.                         UBYTE reserved;
  749.                         /* Below fields saved by >= V7 */
  750.                         ULONG long_repeat;
  751.                         ULONG long_replen;
  752.                     };
  753.  
  754.                     hold, decay = hold/decay values of the
  755.                                   instrument
  756.  
  757.                     suppress_midi_off = 0 (FALSE) or not (TRUE)
  758.  
  759.                     finetune    = instrument finetune (-8-+7)
  760.  
  761.                     default_pitch = instrument's default pitch
  762.                                     (0 = ---, 1 = C-1, 2 = C#1...)
  763.  
  764.                     instr_flags = some miscellaneous flags:
  765.                                   SSFLG_LOOP     0x01 (Loop On/Off)
  766.                                   SSFLG_EXTPSET  0x02 (Ext. Preset)
  767.                                   SSFLG_DISABLED 0x04 (Disabled)
  768.                                   SSFLG_PINGPONG 0x08 (Ping-pong looping)
  769.  
  770.                     long_midi_preset = overrides the preset in the
  771.                                        song structure (allows ext.
  772.                                        presets)
  773.  
  774.                     output_device = instrument's output device,
  775.                                     currently the following exist:
  776.                                     OUTPUT_STD  0 (standard Amiga audio)
  777.                                     OUTPUT_MD16 1 (Aura)
  778.                                     OUTPUT_TOCC 2 (Toccata)
  779.  
  780.                     reserved = zero, at the moment
  781.  
  782.                     long_repeat, long_replen = override repeat and repeat
  783.                             length values in the song structure. These
  784.                             fields allow long and odd repeat values.
  785.                             (Which are not useful unless mixing or using
  786.                             fast mem playing.)
  787.  
  788.     s_ext_entries   = the size of InstrExt structure array (i.e. the
  789.                       number of InstrExt structures). IMPORTANT: If you are
  790.                       reading MMD3 modules, this value may be greater than
  791.                       63! You should ignore any exp_smp structures above 63
  792.                       in that case! (Making room for > 63 instruments.)
  793.  
  794.     s_ext_entrsz    = the size of each InstrExt structure (in bytes).
  795.  
  796.     annotxt     = pointer to the annotation text (null-terminated).
  797.  
  798.     annolen     = length of 'annotxt', including the terminating \0.
  799.  
  800.     iinfo       = pointer to MMDInstrInfo. Currently the first forty
  801.                   bytes have been defined:
  802.  
  803.                     struct MMDInstrInfo {
  804.                         UBYTE   name[40];
  805.                     };
  806.  
  807.                   name = null-terminated instrument name
  808.  
  809.     i_ext_entries   = the size of the MMDInstrInfo struct array (i.e. the
  810.                       number of MMDInstrInfo structures).
  811.  
  812.     i_ext_entrsz    = the size of each MMDInstrInfo struct in bytes.
  813.  
  814.     jumpmask    = a mask controlling which instruments cause the
  815.                   mouse pointer to jump. E.g. bit #1 = instr. #1.
  816.                   This field has become obsolete in OctaMED Pro.
  817.  
  818.     rgbtable    = pointer to eight UWORDs (screen colors) to be
  819.                   passed to LoadRGB4() routine.
  820.  
  821.     channelsplit    = this longword is divided to four boolean bytes,
  822.                       controlling channel splitting in OctaMED 5 - 8 chnl
  823.                       modes. (A non-zero byte means that the channel is
  824.                       NOT splitted.) Currently only the following
  825.                       combinations should be used:
  826.  
  827.                       0x00000000 (8 channels (or normal 4 channel mode))
  828.                       0x000000FF (7 channels)
  829.                       0x0000FFFF (6 channels)
  830.                       0x00FFFFFF (5 channels)
  831.  
  832.     n_info      = pointer to NotationInfo structure (used only in
  833.                   OctaMED V2.0 and later). It contains some info for
  834.                   the notation editor.
  835.                 
  836.                     struct NotationInfo {
  837.                         UBYTE n_of_sharps;
  838.                         UBYTE flags;
  839.                         WORD  trksel[5];
  840.                         UBYTE trkshow[16];
  841.                         UBYTE trkghost[16];
  842.                         BYTE  notetr[63];
  843.                         UBYTE pad;
  844.                     };
  845.  
  846.                   n_of_sharps   = number of sharps or flats (0 - 6)
  847.                   flags     = misc. bits, these are defined:
  848.                               NFLG_FLAT   1
  849.                            (= use flats instead of sharps)
  850.                               NFLG_3_4    2
  851.                            (= display 12 lines instead of 16)
  852.  
  853.                   trksel    = the number of the selected track,
  854.                               for each display preset
  855.                               (-1 = no track selected)
  856.  
  857.                   trkshow   = tracks shown (five bits used in
  858.                               each byte, bit #0 = preset 1, etc.)
  859.  
  860.                   trkghost  = tracks ghosted (as in 'trkshow')
  861.  
  862.                   notetr    = note transpose value for each
  863.                               instrument (-24 - +24). If bit 6 is
  864.                               negated, the instrument is hidden.
  865.  
  866.                   pad       = possibly holding info about struct
  867.                               expansions in the future. Don't touch!
  868.  
  869.     songname    = song name of the current song (0-terminated).
  870.                   Each song of a multi-module can have a different
  871.                   name.
  872.  
  873.     songnamelen = song name length (including the terminating zero).
  874.  
  875.     dumps       = MIDI dump data (created using OctaMED Pro MIDI
  876.                   message editor). The 'dumps' field points to the
  877.                   following struct:
  878.  
  879.                     struct MMDDumpData {
  880.                         UWORD   numdumps;
  881.                         UWORD   reserved[3];
  882.                     };
  883.  
  884.                   Immediately after this struct, there are 'numdumps'
  885.                   pointers to the following struct:
  886.  
  887.                     struct MMDDump {
  888.                         ULONG   length;
  889.                         UBYTE   *data;
  890.                         UWORD   ext_len;
  891.                         /* if ext_len >= 20: */
  892.                         UBYTE   name[20];
  893.                     };
  894.  
  895.                   length    = length of the MIDI message dump.
  896.  
  897.                   data      = pointer to the actual MIDI dump
  898.                               data.
  899.  
  900.                   ext_len   = MMDDump struct extension length.
  901.                               For flexible future expansion.
  902.  
  903.                   (if ext_len >= 20, the following fields exist)
  904.  
  905.                   name      = name of the dump.
  906.  
  907.     mmdinfo     = provides more information about the song that annotxt.
  908.                   Currently allows a text file to be attached. The
  909.                   structure MMDInfo is:
  910.  
  911.                   struct MMDInfo {
  912.                       struct MMDInfo *next;
  913.                       UWORD reserved;
  914.                       UWORD type;
  915.                       ULONG length;
  916.                   /* data follows... */
  917.                   };
  918.  
  919.                   next = pointer to the next MMDInfo structure. However,
  920.                          OctaMED 6 only supports one attachment, so this
  921.                          field is not used at the moment. May change in
  922.                          the future.
  923.  
  924.                   reserved = 0
  925.  
  926.                   type = data type. This is for maximum flexibility for
  927.                          future expansions. Currently only type 1 (ASCII
  928.                          text) is supported. Other types should be ignored.
  929.  
  930.                          ASCII is standard Amiga ISO ASCII. Lines terminated
  931.                          by a single '\n'. The text is null terminated. No
  932.                          tabs allowed (ListView gadgets can't display them).
  933.  
  934.                   length = data length in bytes.
  935.  
  936.     mmdrexx     = contains the embedded ARexx commands (triggered by the
  937.                   song). 'mmdrexx' points to this structure:
  938.  
  939.                   struct MMDARexx {
  940.                       UWORD  res;    /* reserved, must be zero! */
  941.                       UWORD  trigcmdlen; /* size of trigcmd entries
  942.                                             (MUST be used!!) */
  943.                       struct MMDARexxTrigCmd *trigcmd; /* a chain of
  944.                                          MMDARexxTrigCmds, or NULL */
  945.                   };
  946.  
  947.                   'trigcmdlen' is the size of trigcmd entries. You must
  948.                   write sizeof(struct MMDARexxTrigCmd) to this field when
  949.                   writing modules.
  950.  
  951.                   struct MMDARexxTrigCmd is:
  952.  
  953.                   struct MMDARexxTrigCmd {
  954.                       struct MMDARexxTrigCmd *next; /* the next command,
  955.                                                       or NULL */
  956.                       UBYTE cmdnum; /* command number (01..FF) */
  957.                       UBYTE pad;
  958.                       WORD cmdtype; /* command type (OMACTION_...) */
  959.                       STRPTR cmd; /* command, or NULL */
  960.                       STRPTR port; /* port, or NULL */
  961.                       UWORD cmd_len; /* length of 'cmd' string (without
  962.                               term. 0) */
  963.                       UWORD port_len; /* length of 'port' string (without
  964.                               term. 0) */
  965.                   }; /* current (V7) structure size: 20 */
  966.  
  967.                   next = Pointer to the next instance of this structure.
  968.                          Use when reading.
  969.  
  970.                   cmdnum = Command (data byte) number for sending this
  971.                            command (01...FF).
  972.  
  973.                   cmdtype = Command type (see modplayer.h).
  974.  
  975.                   cmd = Command string (pointer), NULL if none.
  976.  
  977.                   port = Port name string (pointer), NULL if none.
  978.                          (For OMACTION_CMDEXT.)
  979.  
  980.                   cmd_len, port_len = lengths of the above two strings
  981.  
  982.     mmdcmd3x    = This structure contains the settings for command 3x.
  983.                   The information is in the following structure:
  984.  
  985.                   struct MMDMIDICmd3x {
  986.                       UBYTE struct_vers; // current version = 0
  987.                       UBYTE pad;
  988.                       UWORD num_of_settings; // number of Cmd3x settings
  989.                                              // (currently set to 15)
  990.                       UBYTE *ctrlr_types; // controller types [ignore
  991.                                           // unknown types!!]
  992.                       UWORD *ctrlr_numbers; // controller numbers
  993.                   };
  994.  
  995.                   struct_vers = 0
  996.  
  997.                   num_of_settings = number of controller settings
  998.                                     (could be > 15 in the future)
  999.  
  1000.                   ctrlr_types = pointer to a UBYTE array of controller
  1001.                                 types (see modplayer.h for MCS_TYPE_xx
  1002.                                 definitions).
  1003.  
  1004.                   ctrlr_numbers = pointer to a UWORD array of controller
  1005.                                   numbers
  1006.  
  1007.     reserved2   = future expansion fields, that MUST be zero now.
  1008.  
  1009. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1010. Finally, here is a collection of the most important rules you should obey
  1011. when handling MMD's:
  1012.  
  1013.     * Always use pointers, not absolute offsets.
  1014.  
  1015.     * Check that a pointer is nonzero before accessing anything it
  1016.       points to.
  1017.  
  1018.     * When writing, set undefined/reserved bits and bytes to zero.
  1019.       When reading, mask out undefined bits, and don't use undefined
  1020.       fields.
  1021.  
  1022.     * When writing, always align everything to even boundaries.
  1023.  
  1024.     * When writing, always write the song structure.
  1025.  
  1026.     * Remember to handle error situations correctly (in all programs,
  1027.       not only when handling MMDs ;^)
  1028.  
  1029. If you don't understand some part of this file completely, try saving a
  1030. module and examine the file with a file editor. This way you can learn easily
  1031. about the file format of MED/OctaMED.
  1032.  
  1033. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1034.